tramp is available under the URL below.
There is also a Savannah project page.
The package has been used successfully on GNU Emacs 22, GNU Emacs 23, XEmacs 21 (starting with 21.4), and SXEmacs 22.
The package was intended to work on Unix, and it really expects a Unix-like system on the remote end (except the smb and imap methods), but some people seemed to have some success getting it to work on MS Windows XP/Vista/7 GNU Emacs.
In the backstage, tramp needs a lot of operations on the remote host. The time for transferring data from and to the remote host as well as the time needed to perform the operations there count. In order to speed up tramp, one could either try to avoid some of the operations, or one could try to improve their performance.
Use an external method, like scpc.
Use caching. This is already enabled by default.
Information about the remote host as well as the remote files
are cached for reuse. The information about remote hosts is
kept in the file specified in
tramp-persistency-file-name. Keep this file. If
you are confident, that files on remote hosts are not changed
out of GNU Emacs' control, set
remote-file-name-inhibit-cache to
nil.
Disable version control. If you access remote files which are not under version control, a lot of check operations can be avoided by disabling VC. This can be achieved by
(setq vc-ignore-dir-regexp
(format "\\(%s\\)\\|\\(%s\\)"
vc-ignore-dir-regexp
tramp-file-name-regexp))
Disable excessive traces. The default trace level of
tramp, defined in the variable
tramp-verbose, is 3. You should increase this
level only temporarily, hunting bugs.
When tramp does not connect to the remote host, there are three reasons heading the bug mailing list:
tramp needs to recognize the prompt on the remote machine after execution any command. This is not possible, when the prompt contains unknown characters like escape sequences for coloring. This should be avoided on the remote side. See Remote shell setup. for setting the regular expression detecting the prompt.
You can check your settings after an unsuccessful connection by switching to the tramp connection buffer *tramp/foo*, setting the cursor at the top of the buffer, and applying the expression
M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))
If it fails, or the cursor is not moved at the end of the buffer, your prompt is not recognized correctly.
A special problem is the zsh, which uses left-hand side and right-hand side prompts in parallel. Therefore, it is necessary to disable the zsh line editor on the remote host. You shall add to ~/.zshrc the following command:
[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
When the remote machine opens an echoing shell, there
might be control characters in the welcome message.
tramp tries to suppress such
echoes via the stty -echo command, but
sometimes this command is not reached, because the echoed
output has confused tramp
already. In such situations it might be helpful to use
the sshx or
scpx methods,
which allocate a pseudo tty. See Inline
methods.
On some few systems, the implementation of
process-send-string seems to be broken for
longer strings. It is reported for HP-UX, FreeBSD and
Tru64 Unix, for example. This case, you should customize
the variable tramp-chunksize to 500. For a
description how to determine whether this is necessary
see the documentation of
tramp-chunksize.
Additionally, it will be useful to set
file-precious-flag to t for
tramp files. Then the file
contents will be written into a temporary file first,
which is checked for correct checksum.
(add-hook
'find-file-hooks
'(lambda ()
(when (file-remote-p default-directory)
(set (make-local-variable 'file-precious-flag) t))))
When your network connection is down, ssh sessions might hang. tramp cannot detect it safely, because it still sees a running ssh process. Timeouts cannot be used as well, because it cannot be predicted, how long a remote command will last, for example when copying very large files.
Therefore, you must configure the ssh process to die in such a case. The following entry in ~/.ssh/config would do the job:
Host *
ServerAliveInterval 5
When you log in to the remote machine, do you see the output of ls in color? If so, this may be the cause of your problems.
ls outputs ANSI escape sequences that your terminal emulator interprets to set the colors. These escape sequences will confuse tramp however.
In your .bashrc, .profile or equivalent on the remote machine you probably have an alias configured that adds the option --color=yes or --color=auto.
You should remove that alias and ensure that a new login does not display the output of ls in color. If you still cannot use filename completion, report a bug to the tramp developers.
tramp uses globbing for some operations. (Globbing means to use the shell to expand wildcards such as `*.c'.) This might create long command lines, especially in directories with many files. Some shells choke on long command lines, or don't cope well with the globbing itself.
If you have a large directory on the remote end, you may wish to execute a command like ‘ls -d * ..?* > /dev/null’ and see if it hangs. Note that you must first start the right shell, which might be /bin/sh, ksh or bash, depending on which of those supports tilde expansion.
The following snippet can be put in your ~/.emacs file. It makes GNU Emacs beep after reading from or writing to the remote host.
(defadvice tramp-handle-write-region
(after tramp-write-beep-advice activate)
"Make tramp beep after writing a file."
(interactive)
(beep))
(defadvice tramp-handle-do-copy-or-rename-file
(after tramp-copy-beep-advice activate)
"Make tramp beep after copying a file."
(interactive)
(beep))
(defadvice tramp-handle-insert-file-contents
(after tramp-insert-beep-advice activate)
"Make tramp beep after inserting a file."
(interactive)
(beep))
When you are working with ‘root’ privileges, it might be useful to get an indication in the buffer's modeline. The following code, tested with GNU Emacs 22.1, does the job. You should put it into your ~/.emacs:
(defun my-mode-line-function ()
(when (string-match "^/su\\(do\\)?:" default-directory)
(setq mode-line-format
(format-mode-line mode-line-format 'font-lock-warning-face))))
(add-hook 'find-file-hooks 'my-mode-line-function)
(add-hook 'dired-mode-hook 'my-mode-line-function)
The following code has been tested with GNU Emacs 22.1. You should put it into your ~/.emacs:
(defconst my-mode-line-buffer-identification
(list
'(:eval
(let ((host-name
(if (file-remote-p default-directory)
(tramp-file-name-host
(tramp-dissect-file-name default-directory))
(system-name))))
(if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
(substring host-name 0 (match-beginning 1))
host-name)))
": %12b"))
(setq-default
mode-line-buffer-identification
my-mode-line-buffer-identification)
(add-hook
'dired-mode-hook
'(lambda ()
(setq
mode-line-buffer-identification
my-mode-line-buffer-identification)))
Since GNU Emacs 23.1, the mode line contains an indication
if default-directory for the current buffer is
on a remote host. The corresponding tooltip includes the name
of that host. If you still want the host name as part of the
mode line, you can use the example above, but the
:eval clause can be simplified:
'(:eval
(let ((host-name
(or (file-remote-p default-directory 'host)
(system-name))))
(if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
(substring host-name 0 (match-beginning 1))
host-name)))
GNU Emacs computes the dired options depending on the local host you are working. If your ls command on the remote host does not understand those options, you can change them like this:
(add-hook
'dired-before-readin-hook
'(lambda ()
(when (file-remote-p default-directory)
(setq dired-actual-switches "-al"))))
Sometimes, tramp starts ksh on the remote host for tilde expansion. Maybe ksh saves the history by default. tramp tries to turn off saving the history, but maybe you have to help. For example, you could put this in your .kshrc:
if [ -f $HOME/.sh_history ] ; then
/bin/rm $HOME/.sh_history
fi
if [ "${HISTFILE-unset}" != "unset" ] ; then
unset HISTFILE
fi
if [ "${HISTSIZE-unset}" != "unset" ] ; then
unset HISTSIZE
fi
Let's say you need regularly access to /ssh:news @news.my.domain:/opt/news/etc, which is boring to type again and again. The following approaches can be mixed:
You can define default methods and user names for hosts, (see Default Method, see Default User):
(setq tramp-default-method "ssh"
tramp-default-user "news")
The file name left to type would be C-x C-f /news.my.domain:/opt/news/etc.
Note, that there are some useful settings already. Accessing your local host as ‘root’ user, is possible just by C-x C-f /su::.
Several connection methods (i.e. the programs used) offer powerful configuration possibilities (see Customizing Completion). In the given case, this could be ~/.ssh/config:
Host xy
HostName news.my.domain
User news
The file name left to type would be C-x C-f /ssh :xy:/opt/news/etc. Depending on files in your directories, it is even possible to complete the host name with C-x C-f /ssh:x <TAB>.
File names typed in the minibuffer can be expanded by environment variables. You can set them outside GNU Emacs, or even with Lisp:
(setenv "xy" "/ssh:news
@news.my.domain:/opt/news/etc/")
Then you need simply to type C-x C-f $xy <RET>, and here you are. The disadvantage is, that you cannot edit the file name, because environment variables are not expanded during editing in the minibuffer.
You can define your own key sequences in GNU Emacs, which can be used instead of C-x C-f:
(global-set-key
[(control x) (control y)]
(lambda ()
(interactive)
(find-file
(read-file-name
"Find Tramp file: "
"/ssh:news
@news.my.domain:/opt/news/etc/"))))
Simply typing C-x C-y would initialize the minibuffer for editing with your beloved file name.
See also the Emacs Wiki for a more comprehensive example.
It is possible to define an own abbreviation list for expanding file names:
(add-to-list
'directory-abbrev-alist
'("^/xy" . "/ssh:news
@news.my.domain:/opt/news/etc/"))
This shortens the file openening command to C-x C-f /xy <RET>. The disadvantage is, again, that you cannot edit the file name, because the expansion happens after entering the file name only.
The abbrev-mode gives more flexibility
for editing the minibuffer:
(define-abbrev-table 'my-tramp-abbrev-table
'(("xy" "/ssh:news
@news.my.domain:/opt/news/etc/")))
(add-hook
'minibuffer-setup-hook
'(lambda ()
(abbrev-mode 1)
(setq local-abbrev-table my-tramp-abbrev-table)))
(defadvice minibuffer-complete
(before my-minibuffer-complete activate)
(expand-abbrev))
;; If you use partial-completion-mode
(defadvice PC-do-completion
(before my-PC-do-completion activate)
(expand-abbrev))
After entering C-x C-f xy <TAB>, the minibuffer is expanded, and you can continue editing.
Bookmarks can be used to visit Tramp files or directories.
When you have opened /ssh :news @news.my.domain:/opt/news/etc/, you should save the bookmark via <menu-bar> <edit> <bookmarks> <set>.
Later on, you can always navigate to that bookmark via <menu-bar> <edit> <bookmarks> <jump>.
recentf remembers visited places.
You could keep remote file names in the recent list without checking their readability through a remote access:
(recentf-mode 1)
The list of files opened recently is reachable via <menu-bar> <file> <Open Recent>.
filecache remembers visited places. Add the directory into the cache:
(eval-after-load "filecache"
'(file-cache-add-directory
"/ssh:news
@news.my.domain:/opt/news/etc/"))
Whenever you want to load a file, you can enter C-x C-f C-<TAB> in the minibuffer. The completion is done for the given directory.
bbdb has a built-in feature for Ange-FTP files, which works also for tramp.
You need to load bbdb:
(require 'bbdb)
(bbdb-initialize)
Then you can create a BBDB entry via M-x bbdb-create-ftp-site. Because BBDB is not prepared for tramp syntax, you must specify a method together with the user name, when needed. Example:
M-x bbdb-create-ftp-site <RET>
Ftp Site: news.my.domain <RET>
Ftp Directory: /opt/news/etc/ <RET>
Ftp Username: ssh:news <RET>
Company: <RET>
Additional Comments: <RET>
When you have opened your BBDB buffer, you can access such an entry by pressing the key <F>.
I would like to thank all tramp users, who have contributed to the different recipes!
You can configure Emacs Client doing this.
On the remote host, you start the Emacs Server:
(require 'server)
(setq server-host (system-name)
server-use-tcp t)
(server-start)
Make sure, that the result of (system-name)
can be resolved on your local host; otherwise you might use a
hard coded IP address.
The resulting file ~/.emacs.d/server/server must be copied to your local host, at the same location. You can call then the Emacs Client from the command line:
emacsclient /ssh:user
@host:/file/to/edit
user and host shall be related
to your local host.
If you want to use Emacs Client also as editor for other programs, you could write a script emacsclient.sh:
#!/bin/sh
emacsclient /ssh:$(whoami)
@$(hostname --fqdn):$1
Then you must set the environment variable
EDITOR pointing to that script:
export EDITOR=/path/to/emacsclient.sh
Shame on you, why did you read until now?
(setq tramp-default-method "ftp")
tramp-mode to
nil:
(setq tramp-mode nil)